docs: document the session-scoped routing endpoint for manual use by joch · Pull Request #21 · opper-ai/cli

joch · 2026-07-01T13:22:25Z

What

Adds a "Routing through a session without the CLI" section to the README, documenting the /v3/session/<id>/… endpoint that opper launch targets under the hood — so users can replicate the routing by hand with any OpenAI-, Responses-, or Anthropic-shaped client.

Covers:

The URL shape https://api.opper.ai/v3/session/<session-id>[/<tag>:<value>…]/<native-path>
The sess_<uuid> id format (server rejects other forms with 400 {"error":"invalid session id"})
Tags as path segments, Authorization: Bearer auth
A raw curl example and OPENAI_BASE_URL / ANTHROPIC_BASE_URL env wiring
A wire-shape → native-path → full-URL table

Also corrects the stale → /v3/compat launch annotations: every launchable agent now routes through /v3/session/<id>/… at spawn time, except Claude Desktop, which still bakes /v3/compat into its persistent GUI profile (claude-desktop.ts:238).

Verification

Grounded in live probes against the API (not just the client code):

POST /v3/session/<sess_uuid>/chat/completions → 200 with cost, usage, and meta.trace_uuid
Bare UUID / malformed id → 400 {"error":"invalid session id"}
/v1/messages and /responses routes confirmed present under the session prefix
Tag path segments (/team:growth/…) accepted

Note: the /v3/session/... route is not currently in the public /v3/openapi.yaml spec.

Docs-only change.

https://claude.ai/code/session_01Dd669tGULj45v4CaKBAvGU

Add a "Routing through a session without the CLI" section to the README explaining the /v3/session/<id>/… endpoint that `opper launch` targets: URL shape, sess_<uuid> id validation, tag path segments, bearer auth, a raw curl example, and env-var wiring for OpenAI/Anthropic-shaped agents. Also correct the stale `→ /v3/compat` launch annotations: every launchable agent now routes through /v3/session/<id>/… except Claude Desktop, which still bakes /v3/compat into its persistent GUI profile. Claude-Session: https://claude.ai/code/session_01Dd669tGULj45v4CaKBAvGU

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a0aa3a53c2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-07-01T13:25:28Z

+# OpenAI-shaped agents (OpenCode, Hermes, Pi, …)
+export OPENAI_BASE_URL="https://api.opper.ai/v3/session/$SID"
+export OPENAI_API_KEY="$OPPER_API_KEY"


Don't document OPENAI_ env vars for these agents*

For the listed OpenAI-shaped agents, users following this manual setup won't actually route through the session URL: the adapters wire OpenCode by rewriting provider.opper.options.baseURL in setSessionBaseUrl (src/agents/opencode.ts), Hermes by writing base_url plus key_env: "OPPER_API_KEY" in writeOpperConfig (src/agents/hermes.ts), and Pi by writing baseUrl/apiKey in setOpperProvider plus exporting OPPER_BASE_URL for the extension (src/agents/pi.ts). I only inspected these adapters, and none of them consume OPENAI_BASE_URL/OPENAI_API_KEY, so the README will mislead users trying to reproduce opper launch manually for the agents named in the comment.

Useful? React with 👍 / 👎.

Good catch — confirmed against the adapters. Split the section: env-var clients (generic OpenAI SDKs + Claude Code, which does read ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN) vs config-file agents (OpenCode/Hermes/Pi/OpenClaw), which take the base URL from their own provider config rather than OPENAI_* env vars. Fixed in 20de977.

@codex review

The manual "point a client at it" example listed OpenCode, Hermes, and Pi next to OPENAI_BASE_URL/OPENAI_API_KEY, but those adapters take the base URL from their own provider config files, not those env vars. Split the section into env-var clients (generic OpenAI SDKs, Claude Code) and config-file agents (OpenCode, Hermes, Pi, OpenClaw) so the manual setup actually routes. Addresses Codex review feedback. Claude-Session: https://claude.ai/code/session_01Dd669tGULj45v4CaKBAvGU

joch · 2026-07-01T13:27:07Z

Addressed the OPENAI_* env-var feedback in 20de977 — split into env-var clients vs config-file agents. @codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 20de977d83

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-07-01T13:30:33Z


+## Routing through a session without the CLI
+
+`opper launch` is a thin convenience wrapper. Under the hood it does one thing: it mints a session id and points the agent's inference base URL at a **session-scoped** Opper endpoint, then lets the agent's own SDK speak its native protocol on top. You can wire this up by hand with any OpenAI-, Responses-, or Anthropic-shaped client — no CLI required.


Exclude Claude Desktop from session-launch claim

For opper launch claude-desktop, this is not what happens: claudeDesktop.spawn() ignores routing.baseUrl and writeGatewayProfile() hard-codes OPPER_COMPAT_URL, so Desktop traffic keeps using the persistent /v3/compat profile rather than the freshly minted /v3/session/<id> URL. As written, the blanket opper launch description can make users expect per-launch session grouping and summaries for Claude Desktop even though that adapter is the documented exception.

Useful? React with 👍 / 👎.

Agreed — qualified both the Agents intro and the section opener to exclude Claude Desktop (persistent /v3/compat profile, no per-launch session). Fixed in the latest commit.

@codex review

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 46b01a4037

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review

Mark a draft as ready

Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

The prose claimed every `opper launch` runs inside a fresh session, but Claude Desktop is the documented exception (persistent /v3/compat GUI profile, ignores routing.baseUrl). Qualify both the Agents intro and the session-routing section opener so users don't expect per-launch session grouping for Desktop. Addresses Codex review feedback. Claude-Session: https://claude.ai/code/session_01Dd669tGULj45v4CaKBAvGU

chatgpt-codex-connector Bot reviewed Jul 1, 2026

View reviewed changes

joch merged commit 5eb91d9 into main Jul 1, 2026
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: document the session-scoped routing endpoint for manual use#21

docs: document the session-scoped routing endpoint for manual use#21
joch merged 3 commits into
mainfrom
doc-sessions

joch commented Jul 1, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 1, 2026

Uh oh!

joch Jul 1, 2026

Uh oh!

joch commented Jul 1, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 1, 2026

Uh oh!

joch Jul 1, 2026

Uh oh!

chatgpt-codex-connector Bot Jul 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		## Routing through a session without the CLI

		`opper launch` is a thin convenience wrapper. Under the hood it does one thing: it mints a session id and points the agent's inference base URL at a session-scoped Opper endpoint, then lets the agent's own SDK speak its native protocol on top. You can wire this up by hand with any OpenAI-, Responses-, or Anthropic-shaped client — no CLI required.

Uh oh!

Conversation

joch commented Jul 1, 2026

What

Verification

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

joch Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

joch commented Jul 1, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

joch Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant